<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta name="description" content="A Javadoc-like Documentation Tool for for all versions of XSLT (1.0, 1.1, 2.0). Available for free on a GPL licence. " />
		<meta name="author" content="P&amp;P Software GmbH" />
		<meta name="keywords" content="XSLT, XSLT documentation, XSLT 2.0, Open Source, Documenting XSLT, xsltdoc, xsldoc, Javadoc, Doxygen, xdoc, gpl" />
    <title>
      XSLTdoc - A Code Documentation Tool for XSLT - Main Page
    </title>
    <link href="XSLTdoc.css" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <div id="navbar">
      <div id="menuLinks">
        <a class="menuLinkCurrent" href="index.html">Main Page</a><a class="menuLink" href="stylesheetList.html">Stylesheet List</a><a class="menuLink" href="functionTemplateList.html">Function/Template List</a>
      </div>
    </div>
    <div id="content">
      <div id="mainPage"><h1>XSLTdoc - A Code Documentation Tool for XSLT</h1>
    <p>
      XSLTdoc is a Javadoc-like tool for all versions of XSLT (1.0,
      1.1, 2.0). It defines
      conventions to document XSL "code elements" directly in the source code. These
      "documentation elements" are then extracted by the XSLTdoc
      tool to build a documentation consisting of several linked HTML pages
      which provide easy browsing through the documentation. The
      XSLT source code is available with syntax highlighting.
    </p>
    XSLTdoc was developed in a project funded by the European Space Agency under contract 18664/04/NL/LvH.
    <p>
      XSLTdoc is written in XSLT 2.0 and is documented with XSLTdoc (This page). It is freely available on a GPL licence.
    </p>
    <p>
      <a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=124907&amp;type=1" width="88" height="31" border="0" alt="SourceForge.net Logo" /></a>    
    </p>
    <p>
      <a href="http://sourceforge.net/projects/xsltdoc/">Project Page</a> on SourceForge.
    </p>
    <p>
      Please use <b><a href="https://sourceforge.net/forum/?group_id=124907">the Forum</a></b> on SourceForge if you need help or have comments on XSLTdoc.
    </p>
    <h2>Table of Contents</h2>
    <ul>
      <li>
        <a href="#News">News</a>
      </li>
      <li>
        <a href="#Features">Features</a>
      </li>
      <li>
        <a href="#InstallingXSLTdoc">Installing XSLTdoc</a>
      </li>
      <li>
        <a href="#RunningXSLTdoc">Running XSLTdoc</a>
      </li>
      <li>
        <a href="#DocumentingTheCode">Documenting the code</a>
      </li>
      <li>
        <a href="#Download">Download</a>
      </li>
      <li>
        <a href="#CopyrightAndLicence">Copyright And License</a>
      </li>
    </ul>
    <h2><a name="News">News</a></h2>
      <h3>January 16, 2009</h3>
      <p>A bugfix release 1.2.1 is available for <a href="#Download">download</a>.</p>
      <p>Changelog</p>
      <ul>
        <li>Changed output format from XML to XHTML</li>
        <li>Changed output encoding to UTF-8</li>
        <li>Fixed a bug where xd:detail was not printed</li>
        <li><code>xml:xd</code> inline tag supports an <code>href</code> attribute which allows to include external XML markup</li>
        <li>Enabled <a href="https://sourceforge.net/forum/?group_id=124907">the Forum</a> on sourceforge</li>
      </ul>
    
      <h3>December 14, 2007</h3>
      <p>Release 1.2 is available for <a href="#Download">download</a>.</p>
      <p>Thanks to <b>Johannes Katelaan</b> and <b>Sascha Mantscheff</b> for their contributions.</p>
      <p>New Features</p>
      <ul>
        <li>added section for documentation on xsl:variable</li>
        <li>added section for documentation on xsl:attribute-set</li>
        <li>implemented  <code>xd:link</code> for referencing templates</li>
        <li>supports <code>xsl:key</code> elements</li>
      </ul>
      <h3>January 5, 2005</h3>
      <p>Release 1.1 is available for download</p>
      <h3>December 20, 2004</h3>
      <p>Released Version 1.0.1</p>
    <h2><a name="Features">Features</a></h2>
    <ul>
      <li>Documentation is embedded in the XSL program</li>
      <li>Documenting of XSLT 2.0 functions</li>
      <li>Syntax highlighted source code browsing</li>
      <li>Generates documentation a whole set of stylesheets</li>
      <li>Generates documentation for included and imported stylesheets</li>
      <li>Layout is customizeable with CSS stylesheets</li>
      <li>Site layout is based on a customizeable/interchangeable html template</li>
      <li>Easely extensible with new tags</li>
      <li>Open source under GPL license</li>
      <li>Written in XSLT</li>
    </ul>
    
    <h2><a name="InstallingXSLTdoc">Installing XSLTdoc</a></h2>
    <p>Installation of XSLTdoc is simply done by unzipping the XSLTdoc
      distribution file in a dedicated target directory (usually called
      XSLTdoc). </p>
    <h2><a name="RunningXSLTdoc">Running XSLTdoc</a></h2>
    <p>XSLTdoc is written in XSLT 2.0. You need an XSLT 2.0 processor to run it.
      The downloadable package of XSLTdoc includes the free version of the Saxon
      XSLT and XQuery Processor from Saxonica Limited, which needs an installation
      of a java virtual machine to be run.</p>
    <p>
      To generate a documentation for one or more XSLT programs you need to write a 
      configuration file which inlcudes all the information needed for the generation process.
      The configuration file is a simple XML file. Use the template below as a starting 
      point for your own configuration file. Not mandatory elements are marked.</p>
    <div class="source"><pre>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;XSLTdocConfig&gt;
  &lt;Title&gt;The title used on the main page&lt;/Title&gt;
  &lt;Introduction&gt;
    This section is copied to the main documentation page. It can include any HTML tags.
  &lt;/Introduction&gt;
  
  &lt;!-- 
    The absolute or relative path to the target directory 
    where the HTML files are created. If a relative path
    is used it is always relative to the config file.
   --&gt;
  &lt;TargetDirectory path="../doc"/&gt;
  &lt;!-- 
    The absolute or relative path to the source directory.
    This is where the XSLT source files can be found.
    If a relative path is used it is always relative 
    to the config file.
   --&gt;
  &lt;SourceDirectory path="./"/&gt;
  &lt;!-- 
    A list of source code files which shall be documented. 
    Only stylesheets which are not included by another
    have to be listed here. The included stylesheets
    are found automatically by following the include or
    the import statements in the including stylesheet.
    Relative references are relative to the SourceDirectory
    defined above.
   --&gt;
  &lt;RootStylesheets&gt;
    &lt;File href="xsltdoc.xsl"/&gt;
    &lt;File href="test.xsl"/&gt;
  &lt;/RootStylesheets&gt;
  
  &lt;!-- 
    A list of CSS Stylesheet files which should be added to the standard CSS file included (XSLTdoc.css)
    - Not mandatory
    - media attribute optional.
  --&gt;
  &lt;AdditionalCSS&gt;
    &lt;File href="print.css" media="print"/&gt;
  &lt;/AdditionalCSS&gt;
&lt;/XSLTdocConfig&gt;</pre></div>
    <p>
    To start the generation process use the configuration file 
    as the input for the xsltdoc.xsl program. 
    The command using Saxon 8 XSLT processor looks like this (while being in the XSLTdoc installation folder):</p>
    <div class="source"><pre>java -jar lib/saxon8.jar &lt;configuration file&gt; xsl/xsltdoc.xsl</pre></div>
    <p>Fonts, colors and layout of the HTML documentation are defined in two CSS
      files which can be found in the CSS folder of the installation. Copy both
      files to the folder where the documentation was generated. With ant this
      step can easily be automated. See the build.xml ant-file that is used to
      generate the documentation for XSLTdoc as an example:</p>
    <div class="source"><pre>&lt;?xml version="1.0" standalone="yes" ?&gt;
&lt;project name="XSLTdoc" default="xsltdoc" basedir="."&gt;
  &lt;description&gt;Ant Build file for the XSLTdoc program&lt;/description&gt;

  &lt;path id="classpath"&gt;
    &lt;pathelement location="lib/saxon8.jar" /&gt;
    &lt;pathelement path="${java.class.path}" /&gt;
  &lt;/path&gt;

  &lt;target name="xsltdoc"&gt;
    &lt;delete dir="doc" /&gt;
    &lt;copy todir="doc"&gt;
      &lt;fileset dir="css"&gt;
        &lt;filename name="*.css" /&gt;
      &lt;/fileset&gt;
    &lt;/copy&gt;
    &lt;xslt force="true" style="xsl/xsltdoc.xsl" in="xsl/XSLTdocConfig.xml" out="doc/log.txt"&gt;
      &lt;!-- The target directory must be given relative to stylesheet  --&gt;
      &lt;classpath refid="classpath" /&gt;
    &lt;/xslt&gt;
  	&lt;delete dir="doc/log.txt"/&gt;
  &lt;/target&gt;
&lt;/project&gt;</pre></div>
    
    <h2><a name="DocumentingTheCode">Documenting the code</a></h2>
    <p>Documentation elements are written in XML. Because XSLT is expressed in
      XML too, it is necessary to define a new namespace for XSLTdoc to enable a
      XSLT processor to distinguish between documentation and source code. The
      URI for this namespace is
      <code>http://www.pnp-software.com/XSLTdoc</code>. This namespace must be
      declared in any stylesheet which uses XSLTdoc for documenting. Example:</p>
    <div class="source"><pre>&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:xd="http://www.pnp-software.com/XSLTdoc" version="2.0"&gt;
  ...
&lt;xsl:stylesheet&gt;</pre></div>
	<h3>General documenting rules</h3>
    <p>The documentation is normally added before the source element that should
      be documented. Generally this looks like this (with the XSLTdoc namespace
      mapped to <code>xd</code>):</p>
    <div class="source"><pre>&lt;xd:doc&gt;
  ...
&lt;/xd:doc&gt;
&lt;xsl:...&gt;</pre></div>
    <p>Any XSLTdoc documentation is enclosed in a <code>xd:doc</code> element.
      If you just want to write a plain text comment the <code>xd:doc</code> element can contain simple text. 
      Text before the first period is considered as short description, the remaining as detailed description:</p>
    <div class="source"><pre>&lt;xd:doc&gt;
  This is the short description. And here comes a more detailed 
  description that appears in the detailed view of the documentation only.
&lt;/xd:doc&gt;
&lt;xsl:...&gt;</pre></div>
    <p>If you use this technique no HTML elements are allowed in the text. If you want to use HTML tags
      within short and detailed description the text for the short and detailed description needs to enclosed in
      special XSLTdoc tags:</p>
    <div class="source"><pre>&lt;xd:doc&gt;
  &lt;xd:short&gt;This is the short description with &lt;code&gt;HTML tags&lt;/code&gt;.&lt;/xd:short&gt;
  &lt;xd:detail&gt;
    And here comes a &lt;b&gt;more detailed&lt;/b&gt; 
    description showed only in the detailed view of the documentation.
  &lt;xd:detail&gt;
&lt;/xd:doc&gt;
&lt;xsl:...&gt;</pre></div>
	<h3>Stylesheet documentation</h3>
	<p>The documentaion of a stylesheet is the only exception where the documentation 
	is written as a subelement of the target element (xsl:stylesheet). To mark a documentation element
	as a stylesheet documentation the type attribute of the <code>xd:doc</code> element must be set to 'stylesheet'.
	A stylesheet documentation can have the following subelements (properties): xd:author, xd:copyright, xd:cvsId, xd:svnId:</p>
    <div class="source"><pre>&lt;xsl:stylesheet ...&gt;
  &lt;xd:doc <strong>type="stylesheet"</strong>&gt;
    ...
    &lt;xd:author&gt;ibirrer&lt;/xd:author&gt;
    &lt;xd:copyright&gt;P&amp;amp;P Software, 2007&lt;/xd:copyright&gt;
    &lt;xd:cvsId&gt;$Id: XSLTdocConfig.xml 42 2009-01-16 15:02:32Z ibirrer $&lt;/xd:cvsId&gt;
  &lt;xd:doc/&gt;
  ...
&lt;xsl:stylesheet&gt;</pre></div>
	<p>Properties can be added by writing a property extension. See the properties directory of the XSLTdoc
	installation for examples.</p>
    <h3>Stylesheet Parameter</h3>
    <p>
      To document a stylesheet parameter you can use the type attribute of the xd:doc element
      to define its type:</p>
      <div class="source"><pre>&lt;xsl:stylesheet ...&gt;
...
  &lt;xd:doc type="string"&gt;
    A Stylesheet parameter of type string.
  &lt;/xd:doc&gt;
  &lt;xsl:param name="outputDir"/&gt;
  ...
&lt;/xsl:stylesheet&gt;</pre></div>
	<h3>Function/Template Documentation</h3>
    <p>The parameter of a template or a function can be described with a
      <code>xd:param</code> element. The name attribute is obligatory for
      templates and functions while the type attribute is optional for
      template definitions.</p>
    <div class="source"><pre>&lt;xd:doc&gt;
  A template with a parameter of the type string.
  &lt;xd:param type="string"&gt;The string to be processed.&lt;/xd:param&gt;
&lt;/xd:doc&gt;</pre></div>
    

    
    <p>Look at the source code of the XSLTdoc tool for more examples. The source
      code is accessible through this website. Just go to a detailed description
      of a template or function and click on the <i>source</i> link.
    </p>
    <h3>Inline tags</h3>
    <p>You can use so called inline tags to tag special parts inside a <code>xs:short</code> or <code>xd:detail</code> element:</p>
    <p>The xd:xml inline tag can be used to to print print an xml to the output. The whole xml inside the tag is transformed to html by XSLTdoc.</p>
    <div class="source"><pre>&lt;xd:doc&gt;
  &lt;xd:detail&gt;
    The following XML inside the xd:xml tag is printed exactly as it shows here:
    &lt;xd:xml&gt;
&lt;html&gt;
  &lt;head&gt;&lt;/head&gt;
  &lt;body&gt;
    Bla
  &lt;/body&gt;
&lt;/html&gt;
    &lt;/xd:xml&gt;
  &lt;xd:detail&gt;
&lt;/xd:doc&gt;
&lt;xsl:...&gt;</pre></div>
    
    
    <h2><a name="Download">Download</a></h2>
    <p>Downloads are available through the <a href="http://sourceforge.net/project/showfiles.php?group_id=124907&amp;package_id=136566">sourceforge project page</a>.</p>
    <p>By downloading any of these files you are accepting the licence condition stated <a href="#CopyrightAndLicence">below</a>.</p>

    <h2><a name="CopyrightAndLicence">Copyright And Licence</a></h2>
    <p>The software and documenation downloadable from this site is made up of the following items:</p>
    <ul>
      <li>Software and documentation for the XSLTdoc documentation tool. The copyright for these items belongs to <a href="http://www.pnp-software.com/">P&amp;P Software</a>. These items can be downloaded and used under the terms of the <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public Licence</a>.</li>
      <li> The The Saxon XSLT and XQuery Processor from <a href="http://www.saxonica.com/">Saxonica Limited</a>. This software is used and distributed in accordance with the terms of the <a href="http://www.mozilla.org/MPL/">Mozilla Public License Version 1.0</a>.</li>
      <li>The XML to HTML Verbatim Formatter with Syntax Highlighting. This software was downloaded from <a href="http://www.informatik.hu-berlin.de/%7Eobecker/XSLT/">http://www.informatik.hu-berlin.de/~obecker/XSLT/</a>. There was no license information available on this site at the time of downloading (October 2004).</li>
    </ul>
    <p>
      THE XSLTdoc DELIVERABLES ARE PROVIDED "AS IS'' AND ANY EXPRESSED 
      OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 
      NO EVENT SHALL THE PROVIDER OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, 
      INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
      PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 
      TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
      EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
    </p>
  </div>
    </div>
    <div id="footer">
      <div style="float:left">Generated with <a target="_blank" href="http://xsltdoc.sf.net">XSLTdoc 1.2.1</a></div>
      <div style="float:right">
        <a href="http://jigsaw.w3.org/css-validator/">CSS</a>
        |
        <a href="http://validator.w3.org/check?uri=referer">XHTML</a>
        | © 2009, <a target="_blank" href="http://www.pnp-software.com/">P&amp;P Software</a>
      </div>
      <div> </div>
    </div>
  </body>
</html>